docs: Move documentation to inline comments: gdkselection

diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index 4341431194b0c33364abd14731e2b234d9fd4fc9..e835592bcbd4aac5ab90512ebdaf47fd33548a3e 100644 (file)
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -12,5 +12,6 @@ keys.sgml
 pango_interaction.sgml
 pixbufs.sgml
 regions.sgml
+selections.sgml
 visuals.sgml
 windows.sgml

diff --git a/docs/reference/gdk/tmpl/selections.sgml b/docs/reference/gdk/tmpl/selections.sgml
deleted file mode 100644 (file)
index 1ce9b89..0000000
--- a/docs/reference/gdk/tmpl/selections.sgml
+++ /dev/null
@@ -1,279 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Selections
-
-<!-- ##### SECTION Short_Description ##### -->
-Functions for transfering data via the X selection mechanism
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The X selection mechanism provides a way to transfer
-arbitrary chunks of data between programs. 
-A <firstterm>selection</firstterm> is a essentially 
-a named clipboard, identified by a string interned
-as a #GdkAtom. By claiming ownership of a selection,
-an application indicates that it will be responsible
-for supplying its contents. The most common 
-selections are <literal>PRIMARY</literal> and 
-<literal>CLIPBOARD</literal>.
-</para>
-<para>
-The contents of a selection can be represented in
-a number of formats, called <firstterm>targets</firstterm>.
-Each target is identified by an atom. A list of
-all possible targets supported by the selection owner
-can be retrieved by requesting the special target
-<literal>TARGETS</literal>. When a selection is 
-retrieved, the data is accompanied by a type
-(an atom), and a format (an integer, representing
-the number of bits per item).
-See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
-for more information.
-</para>
-<para>
-The functions in this section only contain the lowlevel
-parts of the selection protocol. A considerably more
-complicated implementation is needed on top of this.
-GTK+ contains such an implementation in the functions
-in <literal>gtkselection.h</literal> and programmers
-should use those functions instead of the ones presented 
-here. If you plan to implement selection handling
-directly on top of the functions here, you should refer
-to the X Inter-client Communication Conventions Manual
-(ICCCM).
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### MACRO GDK_SELECTION_PRIMARY ##### -->
-<para>
-A #GdkAtom representing the <literal>PRIMARY</literal> selection.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_SECONDARY ##### -->
-<para>
-A #GdkAtom representing the <literal>SECONDARY</literal> selection.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_CLIPBOARD ##### -->
-<para>
-A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
-</para>
-
-
-
-<!-- ##### MACRO GDK_TARGET_BITMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>BITMAP</literal> selection target.
-</para>
-
-
-
-<!-- ##### MACRO GDK_TARGET_COLORMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
-</para>
-
-
-
-<!-- ##### MACRO GDK_TARGET_DRAWABLE ##### -->
-<para>
-A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
-</para>
-
-
-
-<!-- ##### MACRO GDK_TARGET_PIXMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
-</para>
-
-
-
-<!-- ##### MACRO GDK_TARGET_STRING ##### -->
-<para>
-A #GdkAtom representing the <literal>STRING</literal> selection target.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_ATOM ##### -->
-<para>
-A #GdkAtom representing the <literal>ATOM</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_BITMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>BITMAP</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_COLORMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_DRAWABLE ##### -->
-<para>
-A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_INTEGER ##### -->
-<para>
-A #GdkAtom representing the <literal>INTEGER</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_PIXMAP ##### -->
-<para>
-A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_WINDOW ##### -->
-<para>
-A #GdkAtom representing the <literal>WINDOW</literal> selection type.
-</para>
-
-
-
-<!-- ##### MACRO GDK_SELECTION_TYPE_STRING ##### -->
-<para>
-A #GdkAtom representing the <literal>STRING</literal> selection type.
-</para>
-
-
-
-<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
-<para>
-Sets the owner of the given selection.
-</para>
-
-@owner: a #GdkWindow or %NULL to indicate that the
-        the owner for the given should be unset.
-@selection: an atom identifying a selection.
-@time_: timestamp to use when setting the selection.
-       If this is older than the timestamp given last
-       time the owner was set for the given selection, the 
-       request will be ignored.
-@send_event: if %TRUE, and the new owner is different
-             from the current owner, the current owner
-             will be sent a SelectionClear event.
-@Returns: %TRUE if the selection owner was successfully
-          changed to @owner, otherwise %FALSE.
-
-
-<!-- ##### FUNCTION gdk_selection_owner_set_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@owner: 
-@selection: 
-@time_: 
-@send_event: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
-<para>
-Determines the owner of the given selection.
-</para>
-
-@selection: an atom indentifying a selection.
-@Returns: if there is a selection owner for this window,
-          and it is a window known to the current process,
-          the #GdkWindow that owns the selection, otherwise
-          %NULL. Note that the return value may be owned
-          by a different process if a foreign window
-          was previously created for that window, but
-          a new foreign window will never be created by
-          this call.
-
-
-<!-- ##### FUNCTION gdk_selection_owner_get_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@selection: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_selection_convert ##### -->
-<para>
-Retrieves the contents of a selection in a given
-form.
-</para>
-
-@requestor: a #GdkWindow.
-@selection: an atom identifying the selection to get the
-            contents of.
-@target: the form in which to retrieve the selection.
-@time_: the timestamp to use when retrieving the
-       selection. The selection owner may refuse the
-       request if it did not own the selection at 
-       the time indicated by the timestamp.
-
-
-<!-- ##### FUNCTION gdk_selection_property_get ##### -->
-<para>
-</para>
-
-@requestor: 
-@data: 
-@prop_type: 
-@prop_format: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
-<para>
-Sends a response to SelectionRequest event.
-</para>
-
-@requestor: window to which to deliver response.
-@selection: selection that was requested.
-@target: target that was selected.
-@property: property in which the selection owner stored the
-           data, or %GDK_NONE to indicate that the request
-           was rejected.
-@time_: timestamp.
-
-
-<!-- ##### FUNCTION gdk_selection_send_notify_for_display ##### -->
-<para>
-
-</para>
-
-@display: 
-@requestor: 
-@selection: 
-@target: 
-@property: 
-@time_: 
-
-

diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c
index eed340a02b9ecdf7bd808a910112df28e8b59cf0..fc191aa74f6100f82a57dff2ae7c83c6f4d57920 100644 (file)
--- a/gdk/gdkselection.c
+++ b/gdk/gdkselection.c
@@ -32,6 +32,54 @@
 #include "gdkdisplay.h"
 
 
+/**
+ * SECTION:selections
+ * @Short_description: Functions for transfering data via the X selection mechanism
+ * @Title: Selections
+ *
+ * The X selection mechanism provides a way to transfer arbitrary chunks of
+ * data between programs. A <firstterm>selection</firstterm> is a essentially
+ * a named clipboard, identified by a string interned as a #GdkAtom. By
+ * claiming ownership of a selection, an application indicates that it will
+ * be responsible for supplying its contents. The most common selections are
+ * <literal>PRIMARY</literal> and <literal>CLIPBOARD</literal>.
+ *
+ * The contents of a selection can be represented in a number of formats,
+ * called <firstterm>targets</firstterm>. Each target is identified by an atom.
+ * A list of all possible targets supported by the selection owner can be
+ * retrieved by requesting the special target <literal>TARGETS</literal>. When
+ * a selection is retrieved, the data is accompanied by a type (an atom), and
+ * a format (an integer, representing the number of bits per item).
+ * See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
+ * for more information.
+ *
+ * The functions in this section only contain the lowlevel parts of the
+ * selection protocol. A considerably more complicated implementation is needed
+ * on top of this. GTK+ contains such an implementation in the functions in
+ * <literal>gtkselection.h</literal> and programmers should use those functions
+ * instead of the ones presented here. If you plan to implement selection
+ * handling directly on top of the functions here, you should refer to the
+ * X Inter-client Communication Conventions Manual (ICCCM).
+ */
+
+/**
+ * gdk_selection_owner_set:
+ * @owner: a #GdkWindow or %NULL to indicate that the
+ *   the owner for the given should be unset.
+ * @selection: an atom identifying a selection.
+ * @time_: timestamp to use when setting the selection.
+ *   If this is older than the timestamp given last
+ *   time the owner was set for the given selection, the
+ *   request will be ignored.
+ * @send_event: if %TRUE, and the new owner is different
+ *   from the current owner, the current owner
+ *   will be sent a SelectionClear event.
+ *
+ * Sets the owner of the given selection.
+ *
+ * Returns: %TRUE if the selection owner was successfully
+ *   changed to @owner, otherwise %FALSE.
+ */
 gboolean
 gdk_selection_owner_set (GdkWindow *owner,
                         GdkAtom    selection,
@@ -43,6 +91,21 @@ gdk_selection_owner_set (GdkWindow *owner,
                                              time, send_event);
 }
 
+/**
+ * gdk_selection_owner_get:
+ * @selection: an atom indentifying a selection.
+ *
+ * Determines the owner of the given selection.
+ *
+ * Returns: if there is a selection owner for this window,
+ *   and it is a window known to the current process,
+ *   the #GdkWindow that owns the selection, otherwise
+ *   %NULL. Note that the return value may be owned
+ *   by a different process if a foreign window
+ *   was previously created for that window, but
+ *   a new foreign window will never be created by
+ *   this call.
+ */
 GdkWindow*
 gdk_selection_owner_get (GdkAtom selection)
 {
@@ -50,6 +113,18 @@ gdk_selection_owner_get (GdkAtom selection)
                                              selection);
 }
 
+/**
+ * gdk_selection_send_notify:
+ * @requestor: window to which to deliver response.
+ * @selection: selection that was requested.
+ * @target: target that was selected.
+ * @property: property in which the selection owner stored the
+ *   data, or %GDK_NONE to indicate that the request
+ *   was rejected.
+ * @time_: timestamp.
+ *
+ * Sends a response to SelectionRequest event.
+ */
 void
 gdk_selection_send_notify (GdkNativeWindow requestor,
                           GdkAtom         selection,

diff --git a/gdk/gdkselection.h b/gdk/gdkselection.h
index fc5d4b40e83ed7e08461427692df8ce489e3c53a..897e0c77cf601d1e0f5e87c379e33cc4edbaee4b 100644 (file)
--- a/gdk/gdkselection.h
+++ b/gdk/gdkselection.h
@@ -38,21 +38,116 @@ G_BEGIN_DECLS
 /* Predefined atoms relating to selections. In general, one will need to use
  * gdk_intern_atom
  */
+/**
+ * GDK_SELECTION_PRIMARY:
+ *
+ * A #GdkAtom representing the <literal>PRIMARY</literal> selection.
+ */
 #define GDK_SELECTION_PRIMARY          _GDK_MAKE_ATOM (1)
+
+/**
+ * GDK_SELECTION_SECONDARY:
+ *
+ * A #GdkAtom representing the <literal>SECONDARY</literal> selection.
+ */
 #define GDK_SELECTION_SECONDARY        _GDK_MAKE_ATOM (2)
+
+/**
+ * GDK_SELECTION_CLIPBOARD:
+ *
+ * A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
+ */
 #define GDK_SELECTION_CLIPBOARD        _GDK_MAKE_ATOM (69)
+
+/**
+ * GDK_TARGET_BITMAP:
+ *
+ * A #GdkAtom representing the <literal>BITMAP</literal> selection target.
+ */
 #define GDK_TARGET_BITMAP              _GDK_MAKE_ATOM (5)
+
+/**
+ * GDK_TARGET_COLORMAP:
+ *
+ * A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
+ */
 #define GDK_TARGET_COLORMAP            _GDK_MAKE_ATOM (7)
+
+/**
+ * GDK_TARGET_DRAWABLE:
+ *
+ * A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
+ */
 #define GDK_TARGET_DRAWABLE            _GDK_MAKE_ATOM (17)
+
+/**
+ * GDK_TARGET_PIXMAP:
+ *
+ * A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
+ */
 #define GDK_TARGET_PIXMAP              _GDK_MAKE_ATOM (20)
+
+/**
+ * GDK_TARGET_STRING:
+ *
+ * A #GdkAtom representing the <literal>STRING</literal> selection target.
+ */
 #define GDK_TARGET_STRING              _GDK_MAKE_ATOM (31)
+
+/**
+ * GDK_SELECTION_TYPE_ATOM:
+ *
+ * A #GdkAtom representing the <literal>ATOM</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_ATOM        _GDK_MAKE_ATOM (4)
+
+/**
+ * GDK_SELECTION_TYPE_BITMAP:
+ *
+ * A #GdkAtom representing the <literal>BITMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_BITMAP      _GDK_MAKE_ATOM (5)
+
+/**
+ * GDK_SELECTION_TYPE_COLORMAP:
+ *
+ * A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_COLORMAP    _GDK_MAKE_ATOM (7)
+
+/**
+ * GDK_SELECTION_TYPE_DRAWABLE:
+ *
+ * A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_DRAWABLE    _GDK_MAKE_ATOM (17)
+
+/**
+ * GDK_SELECTION_TYPE_INTEGER:
+ *
+ * A #GdkAtom representing the <literal>INTEGER</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_INTEGER     _GDK_MAKE_ATOM (19)
+
+/**
+ * GDK_SELECTION_TYPE_PIXMAP:
+ *
+ * A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_PIXMAP      _GDK_MAKE_ATOM (20)
+
+/**
+ * GDK_SELECTION_TYPE_WINDOW:
+ *
+ * A #GdkAtom representing the <literal>WINDOW</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_WINDOW      _GDK_MAKE_ATOM (33)
+
+/**
+ * GDK_SELECTION_TYPE_STRING:
+ *
+ * A #GdkAtom representing the <literal>STRING</literal> selection type.
+ */
 #define GDK_SELECTION_TYPE_STRING      _GDK_MAKE_ATOM (31)
 
 /* Selections
@@ -74,6 +169,20 @@ gboolean   gdk_selection_owner_set_for_display (GdkDisplay *display,
 GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display,
                                                GdkAtom     selection);
 
+/**
+ * gdk_selection_convert:
+ * @requestor: a #GdkWindow.
+ * @selection: an atom identifying the selection to get the
+ *   contents of.
+ * @target: the form in which to retrieve the selection.
+ * @time_: the timestamp to use when retrieving the
+ *   selection. The selection owner may refuse the
+ *   request if it did not own the selection at
+ *   the time indicated by the timestamp.
+ *
+ * Retrieves the contents of a selection in a given
+ * form.
+ */
 void      gdk_selection_convert   (GdkWindow    *requestor,
                                    GdkAtom       selection,
                                    GdkAtom       target,